Interface Built Right

╦╔╗ ╦═╗
║╠╩╗╠╦╝
╩╚═╝╩╚═

Interface Built Right

End-to-end design tool for AI coding agents.
Design, build, and validate interfaces — iOS, macOS, and web. Guided builds, deterministic rules, sensor-driven scans.

IBR is an end-to-end design tool for AI coding agents. It guides UI builds with Design Director planning, web and iOS archetype routing, Calm Precision principles, and platform-specific best practices. Built-in visual validation scans live pages, runs interaction assertions, matches mockups, and verifies design intent — Chrome and Safari.

Built on a custom CDP engine — no Playwright. Works from terminal, Codex, Claude Code slash commands, or code. Zero config.

Design Workflow

/ibr:build <topic> orchestrates the full design-to-validation flow:

Preamble — Platform, scope, design mode, archetype hints, UI template, references, density
Optional imagegen concepts — Generates visual concepts only when useful, then requires approval before any concept becomes a visual-target
Design Director — Produces design-intent.json, specialist planning passes, target roles, and validation criteria
Brainstorm & Plan — Guided exploration with platform-specific design rules and a concrete implementation plan
Implement — Build with design guidance: Calm Precision, web/iOS/macOS routers, component patterns, data-viz guidance when needed
Validate — Scan, match wireframe/visual targets, test interactions, iterate until passing

Design Director

The design-director skill is the primary planning layer for page, flow, app, dashboard, and reference-heavy UI work. It selects guidance in a deterministic order, resolves Mockup Gallery references into roles (wireframe-target, visual-target, inspiration, data-reference), and writes specialist planning artifacts under .ibr/builds/<topic>/specialists/.

Specialist passes are used for flow, visual system, interaction states, content states, Mockup Gallery targets, data visualization, and validation. IBR does not create separate tiny agents for buttons, fonts, or individual visual atoms; those stay inside component patterns and design tokens.

Imagegen Concepts

IBR can use imagegen as an upstream concept pass for mood, style, hero/product imagery, and hi-fi variants. Generated concepts are saved under .ibr/builds/<topic>/references/imagegen/ when they are project-bound. They remain inspiration until the user explicitly approves one as a visual-target.

Imagegen does not replace wireframes, accessibility semantics, interaction requirements, or validation. IBR still validates the rendered implementation with scan, interaction, match, and native tools.

Web Design Routing

The web-design-router skill classifies web interfaces into archetypes: SaaS dashboard, data/research tool, editor/workbench, AI agent chat, commerce/checkout, content/publication, and internal admin. Each archetype sets defaults for navigation, density, primary content, mobile behavior, and validation focus.

iOS Design System

The ios-design-router skill classifies apps into 6 archetypes, each with pre-set defaults for navigation, color, typography, motion, and more. Domain reference files provide comprehensive option catalogs:

Domain	Reference	Covers
Navigation	`1_navigation_structure.md`	Tab bars, transitions, sheets, page hierarchy
Content	`2_lists_cards_content.md`	Lists, cards, swipe actions, content resilience
Interactions	`3_buttons_touch_interactions.md`	Buttons, haptics, toggles, forms
Visual	`4_color_surface_typography.md`	Color, gradients, dark mode, typography
Motion & States	`5_motion_states_identity.md`	Loading, onboarding, celebrations, profiles
Task Economy	`6_task_economy.md`	Step counting, flow validation

Two-Tier Architecture

IBR scans return structured data, not just raw element dumps. Two layers run on every scan:

Tier 1 — Deterministic Rule Engine (no LLM)

Runs pure algorithms against the runtime data. Zero tokens. Returns structured verdicts with evidence.

Rule Preset	What It Checks	Algorithm
`wcag-contrast`	Text contrast ratios, AA and AAA	WCAG 2.1 relative luminance
`touch-targets`	Interactive element sizing	44px mobile (WCAG 2.5.5), 24px desktop (WCAG 2.5.8)
`calm-precision`	Gestalt, Signal-to-Noise, Fitts, Hick, Content-Chrome, Cognitive Load	Principle-based checks

Enable via .ibr/rules.json:

{
  "extends": ["wcag-contrast", "touch-targets", "calm-precision"]
}

Or one-off via CLI:

ibr scan http://localhost:3000 --rules wcag-contrast,touch-targets

Output in scanResult.issues with ruleId, severity, message, element, and fix fields.

`ibr ask` — focused verdicts (v3 thesis M1)

Where scan returns the whole tree, ask returns one verdict + minimal evidence. ~600 bytes vs ~19KB for the same page.

ibr ask http://localhost:3000 'is the touch-target compliant'
ibr -v mobile ask http://localhost:3000 'do status indicators follow signal-to-noise'
ibr ask http://localhost:3000 'is design-system token compliance okay'

Closed question vocabulary today (3 questions); unknown questions return verdict: UNCERTAIN with the supported list. Returns {verdict, findings[], meta} with bounds and a fix per finding. Designed for LLM agents — the agent reads a verdict, optionally drills into one finding's evidence, instead of parsing the full DOM.

Tier 2 — Sensor Layer (structured summaries)

Pre-computed summaries that let the model focus on judgment instead of re-discovering patterns:

Sensor	What It Produces	Token Saving
`visualPatterns`	Groups elements by style fingerprint per category (button, link, input, heading)	Replaces N element dumps with M pattern groups
`componentCensus`	Tag/role counts + orphan cursor:pointer elements with no handler	Replaces grep across pages
`interactionMap`	Handler coverage — which interactive-looking elements actually have handlers	Pre-computed from handler detection
`contrast`	WCAG pass/fail grouped, only failures listed	Model skips passing elements
`navigation`	Link structure with depth and counts	Replaces reading Sidebar.tsx
`semanticState`	Wraps existing semantic classifier: page intent, states, available actions	Summary form
`oneLiners`	5-second scannable summary lines	Read first, then drill down

Access in scanResult.sensors. Get summaries-only (cuts ~60% tokens):

ibr scan http://localhost:3000 --output summary

Hydration Waiting

SPAs (Next.js, React, Vue) often render after networkidle fires. IBR's waitForHydration() runs after network idle:

Fast-path marker detection: window.__NEXT_DATA__, React DevTools hook, #__next / #root population
AX tree fingerprint polling until stable for 500ms with at least one interactive element
Settle time (200ms default) to absorb async effects

This eliminates the common "0 elements" result on modern SPAs.

Live Sessions with Auto-Capture

Sessions now auto-capture pre/post interaction by default:

ibr session start http://localhost:3000
ibr session interact --action click --target "Submit"
# Automatically: pre-scan baseline -> action -> URL change detection -> hydration wait -> post-scan -> surface console errors
ibr session close

Each ActionRecord includes:

navigated: boolean — did the click cause a URL change?
urlBefore / urlAfter
actionErrors: string[] — console errors that appeared during this action

Opt out with --no-auto-capture on session start.

Architecture

IBR runs on a custom CDP browser engine — direct Chrome DevTools Protocol over WebSocket. No Playwright, no Puppeteer, no heavyweight browser automation dependencies.

LLM-native features built into the engine:

Feature	What it does
queryAXTree-first resolution	Find elements by semantic name+role (not fragile CSS selectors). 4-tier: CDP-native search → Jaro-Winkler fuzzy → vision fallback
DOM chunking	Filter to interactive/leaf elements, chunk for LLM context windows. 60-70% fewer tokens
Adaptive modality	Scores AX tree quality. High → use text data. Low → include screenshot. Vision only when needed
Resolution cache	Caches intent→element mappings. Same query twice = instant. Clears on navigation
observe()	Preview available actions without executing. Returns serializable descriptors
extract()	Pull structured data from AX tree using schemas

What's New in v1.4.0

Feature	Command / Usage	What it does
Native macOS layout-fill / gap analysis	`scanMacOS` returns `layoutFill[]`; surfaced as `layout-fill:` WARNINGs in `issues[]`	Per-container largest empty horizontal AND vertical band as pixels + % of container extent. Catches the centered-narrow-content bug class (e.g. terminal at 440px centered in 1074px → 317px / 29.5% leading band) that passes screenshot + a11y + touch-target checks. Threshold default 0.12; configurable via `MacOSScanOptions.layoutFill.threshold`
Swift extractor `--analyze-layout`	`ibr-ax-extract --pid N --analyze-layout`	Same algorithm in-Swift; emits `LAYOUT_FINDINGS:<json>` on stderr. Stdout JSON contract unchanged
Drop-in Swift templates	`assets/native/swift-templates/LayoutProbe.swift` + `RenderSwiftUI.swift`	In-process layout dump + wedge-proof `cacheDisplay` PNG when AX/screencapture are wedged. Off-screen SwiftUI → PNG renderer. Pure AppKit/SwiftUI, zero deps

What's New in v0.7.0

Feature	Command	What it does
Interact (MCP + CLI)	`ibr interact` / MCP `interact`	Click, type, fill elements by accessible name. LLM-native interaction
Observe (MCP + CLI)	`ibr observe` / MCP `observe`	Preview all clickable/fillable elements before interacting
Extract (MCP + CLI)	`ibr extract` / MCP `extract`	Read page headings, buttons, inputs, links as structured data
Interact & Verify (MCP)	MCP `interact_and_verify`	Act + capture before/after state diff (elements added/removed)
Interaction assertions	`ibr test-interact`	Click, type, verify — act→verify→screenshot pipeline
Mockup matching	`ibr match`	Compare design mockup PNG against live page (SSIM)
Design verification	`ibr record-change` / `ibr verify-changes`	Capture design intent, verify against reality
Test generation	`ibr generate-test`	Auto-generate .ibr-test.json from page observation
Test runner	`ibr test`	Run declarative test files
Python scripting	`ibr run-script`	Execute Python test scripts with sandboxed resources
Fix-and-iterate	`ibr iterate`	Convergence detection for test-fix cycles
Safari support	`--browser safari`	Cross-browser via safaridriver + macOS AX API
Cross-browser diff	`ibr compare-browsers`	Side-by-side Chrome vs Safari comparison
AX tree coverage	Built into `ibr scan`	Reports AX tree capture %, shadow DOM piercing
Flow testing	`ibr test-search/form/login`	Built-in flows exposed as CLI commands
Playwright removed	--	Zero Playwright dependency, custom CDP engine only

See docs/QUICK-START.md for full usage guide.

What's New in v1.0.0

Feature	Command / Usage	What it does
End-to-end design tool	Positioning update	From "visual testing platform" to design + build + validate
Design Director	`/ibr:build`	Primary design-agent layer with design intent, specialist planning passes, target roles, and validation criteria
Web design router	skill: `web-design-router`	7 web archetypes covering dashboards, research tools, workbenches, AI chat, checkout, content, and admin
Data visualization guidance	skill: `data-visualization`	Chart-worthiness gate, chart routing, attribution, accessibility, and validation rules
iOS design system	`/ibr:build` with platform=iOS	6-archetype router, 7 domain reference files covering navigation, lists, buttons, color, motion, task economy
apple-platform skill	Loaded during iOS builds	Architecture, SwiftData, concurrency, CI/CD, TestFlight — integrated from standalone apple-dev
Deterministic rule engine	`ibr scan --rules wcag-contrast,touch-targets`	WCAG AA/AAA contrast, touch target sizes. No LLM tokens
Sensor layer	`scanResult.sensors`	Visual patterns, component census, interaction map, contrast report, navigation, one-liners
Summary output mode	`ibr scan --output summary`	Returns sensors + verdict, cuts ~60% of tokens
Hydration wait	Built into `ibr scan`	Fixes "0 elements" on SPAs; polls AX tree stability + detects Next.js/React markers
Auto-capture sessions	Default on	Pre/post scan with URL-change detection and console error surfacing

What's New in v0.9.0-alpha

Feature	Command / Skill	What it does
Build command	`/ibr:build <topic>`	Guided UI build — brainstorm, plan, implement, verify in one flow
Capture command	`/ibr:capture <url>`	Capture a named baseline snapshot for any URL
UI guidance	`/ibr:ui-guidance`	On-demand design guidance using IBR scan data
UI brainstorm preamble	skill: `ui-brainstorm-preamble`	Pre-build exploration — explore directions before implementing
UI guidance library	skill: `ui-guidance-library`	Reusable UI guidance patterns and decision aids
Mockup gallery bridge	skill: `mockup-gallery-bridge`	Bridge mockup gallery reviews to IBR scan verification
Mobile web UI	skill: `mobile-web-ui`	Mobile web patterns — responsive design, touch targets, viewport handling
iOS Design	skill: `ios-design`	iOS-specific patterns — SwiftUI conventions, safe areas, haptics
macOS UI	skill: `macos-ui`	macOS-specific patterns — AppKit/SwiftUI, menu bar, window chrome

The Problem

User says "make the buttons blue with 16px Inter font." You build it. But did it work?

Screenshots — you're guessing hex codes from pixels
Manual inspection — slow, error-prone, not automatable
IBR scan — returns backgroundColor: "rgb(59, 130, 246)", fontSize: "16px", fontFamily: "Inter". Done.

How It Works

# User describes what they want -> you build it -> validate with IBR
npx ibr scan http://localhost:3000/page --json

IBR returns structured data per element:

computedStyles — backgroundColor, fontSize, fontFamily, padding, grid, flexbox, etc.
bounds — exact x, y, width, height
interactive — hasOnClick, hasHref, hasReactHandler, isDisabled
a11y — role, ariaLabel, ariaDescribedBy
page-level — pageIntent, auth state, loading state, console errors

For regression, capture before and compare after:

npx ibr start http://localhost:3000    # baseline before changes
# ... edit your code ...
npx ibr check                          # see what changed

Verdicts: MATCH, EXPECTED_CHANGE, UNEXPECTED_CHANGE, LAYOUT_BROKEN

See terminal output

Quick Start

npm install @tyroneross/interface-built-right

That's it. .ibr/ is auto-added to your .gitignore on install.

Validate UI (primary workflow):

npx ibr scan http://localhost:3000 --json    # get structured data

Regression check:

npx ibr start http://localhost:3000    # capture baseline
# ... make changes ...
npx ibr check                          # compare

Sandbox-friendly browser attach

Use connect mode when the agent can reach a Chrome DevTools endpoint but should not spawn Chrome itself.

npx ibr scan http://localhost:3000 \
  --browser-mode connect \
  --cdp-url http://127.0.0.1:9222

You can also provide a browser WebSocket directly:

npx ibr scan http://localhost:3000 \
  --browser-mode connect \
  --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id>

Environment variables are supported for sandboxed agents and wrappers:

IBR_BROWSER_MODE=connect
IBR_CDP_URL=http://127.0.0.1:9222
IBR_WS_ENDPOINT=ws://127.0.0.1:9222/devtools/browser/<id>
IBR_CHROME_PATH=/path/to/chrome

--headed is now the preferred flag for a visible browser window. --sandbox remains as a deprecated alias for backwards compatibility.

Setup as Agent Plugins

IBR works standalone and ships plugin metadata for both Claude Code and Codex. Claude Code gets slash commands, hooks, and the design-validator agent; Codex gets compact routing skills plus MCP/session tools for the same scan, navigation, search, and validation contract.

Claude Code

1. Add the marketplace (one-time):

/plugin marketplace add tyroneross/interface-built-right

2. Install the plugin:

/plugin install ibr@interface-built-right

3. Use in conversation:

Command	What it does
`/ibr:build <topic>`	Guided UI build: preamble → brainstorm → plan → implement → validate
`/ibr:scan <url>`	Full page scan with sensor summaries and optional rule checks
`/ibr:snapshot` / `/ibr:compare`	Before/after regression check
`/ibr:interact`	Click, type, fill by accessible name
`/ibr:match`	Compare rendered UI against a mockup (SSIM)
`/ibr:native-scan`	Scan iOS/watchOS/macOS apps
`/ibr:ui`	Open the web dashboard at localhost:4200

Example:

"Build a daily focus timer for iOS" -> /ibr:build classifies it as a Utility archetype -> routes to iOS design references -> implements with apple-platform patterns -> scans the result, reports any WCAG / touch target / hydration issues.

The plugin hooks run automatic pre/post scans around UI file edits and surface console errors immediately when interactions trigger them.

Codex

Codex consumes .codex-plugin/plugin.json, compact skills under .codex-plugin/skills/, and .codex-plugin/mcp.json. The Codex-compatible agent approach is skills plus MCP tools; Claude-style files under commands/, hooks/, and agents/ are retained for Claude Code and should not be treated as Codex-loaded routing.

Install this checkout as a local Codex plugin:

npm run build
npm run plugin:install-codex

This syncs a slim Codex bundle to ~/plugins/ibr and registers it in ~/.agents/plugins/marketplace.json. Restart Codex after installing. See Codex Plugin Setup for validation steps and failure modes.

Starter prompts:

$ibr Plan this UI with IBR.
$ibr Scan this UI with IBR.
$ibr Validate this design intent.

Use MCP sessions when the agent needs to navigate the current UI state:

{
  "tool": "flow_search",
  "sessionId": "<session id>",
  "query": "pricing plan",
  "userIntent": "Find the plan a buyer would choose",
  "aiValidation": true
}

What IBR Does For You (Plugin Hooks)

When installed as a Claude Code plugin, IBR provides:

Design validation reminders — after UI file edits, nudges to run npx ibr scan to verify against user intent
Scan + screenshot guidance — suggests also running IBR scan for precise property data alongside visual checks
Session end check — reminds if UI work was done but not validated
Bash safety — blocks destructive commands (rm -rf /, git push --force, etc.)
Sensitive path protection — prevents writes to ~/.ssh, ~/.aws, /etc/

Hooks are command-based and live in hooks/hooks.json. They call the repo-local shell scripts under hooks/, which are designed to fail softly when no UI work, no config, or no reachable dev server is present.

What IBR Scan Returns

Element Data (per interactive element)

selector:        Unique CSS path
tagName:         button, a, input, etc.
text:            Visible text content
bounds:          { x, y, width, height } — exact position and size
computedStyles:  backgroundColor, color, fontSize, fontFamily, fontWeight,
                 padding, margin, borderRadius, display, gap, flexDirection,
                 alignItems, justifyContent, gridTemplateColumns, etc.
interactive:     { hasOnClick, hasHref, hasReactHandler, isDisabled, cursor }
a11y:            { role, ariaLabel, ariaDescribedBy, ariaHidden }

Page-Level Data

pageIntent:      auth | form | listing | detail | dashboard | error | landing
state.auth:      { authenticated, username, confidence }
state.loading:   { loading, type: spinner|skeleton|progress }
state.errors:    { hasErrors, errors[], severity }
console:         { errors[], warnings[] }
verdict:         PASS | ISSUES | FAIL

Scan Data vs Screenshots

Each approach catches things the other misses. The best validation uses both.

Where IBR scan wins

Question	Screenshot	IBR Scan
Is this exactly #3b82f6?	Guess from pixels	`backgroundColor: "rgb(59, 130, 246)"`
Is the font 16px Inter?	"Looks about right"	`fontSize: "16px"`, `fontFamily: "Inter"`
Is the button wired up?	Can't tell	`hasOnClick: true`, `hasReactHandler: true`
Are ARIA labels present?	Can't see	`ariaLabel: "Submit form"`, `role: "button"`
Any console errors?	Can't see	`console.errors: []`

Where screenshots win

Question	IBR Scan	Screenshot
Does the page look right?	Can't judge	Visual coherence at a glance
Any rendering glitches?	Computed styles can be correct but render wrong	Sees clipping, overlap, z-index issues
Canvas/SVG/WebGL content?	Not in the DOM	Sees everything rendered
Font rendering quality?	Reports font-family, not rendering	Sees anti-aliasing, kerning
Unexpected visual artifacts?	Only checks what you ask	Catches things you didn't think to check

Best practice: combine both

npx ibr scan http://localhost:3000 --json    # precise property verification
# + screenshot for visual confirmation when needed

For AI agents, scan data is best for precise verification (exact values, handler detection, a11y). Screenshots are best for holistic visual checks. Together they give more confidence than either alone.

CLI Reference

Core Commands

Command	Description
`npx ibr scan <url> --json`	Validate UI — returns structured data
`npx ibr start <url>`	Capture baseline for regression
`npx ibr check`	Compare current state against baseline
`npx ibr serve`	Open web UI at localhost:4200
`npx ibr list`	List all sessions
`npx ibr update`	Accept current as new baseline
`npx ibr clean --older-than 7d`	Clean old sessions

Interactive Sessions

For pages that need clicks, typing, or navigation before validating:

# Start a persistent browser session
npx ibr session:start http://localhost:3000 --name "search-test"

# Interact with it
npx ibr session:type <id> "input[name=search]" "quantum computing"
npx ibr session:click <id> "button[type=submit]"
npx ibr session:wait <id> ".search-results"
npx ibr session:screenshot <id>

All interactive commands

Command	Description
`session:start <url>`	Start browser session
`session:click <id> <selector>`	Click an element
`session:type <id> <selector> <text>`	Type into an element
`session:press <id> <key>`	Press keyboard key
`session:scroll <id> <direction>`	Scroll page
`session:screenshot <id>`	Capture screenshot
`session:wait <id> <selector>`	Wait for element
`session:navigate <id> <url>`	Navigate to URL
`session:html <id>`	Get page HTML
`session:text <id> <selector>`	Extract text content
`session:close <id\|all>`	Close session

Memory (Design Specs)

Store design preferences that IBR enforces during every scan:

# Remember that buttons should be blue
npx ibr memory add "Primary buttons are blue" --category color --property background-color --value "#3b82f6"

# Store font preference
npx ibr memory add "Body font is Inter 16px" --property font-family --value "Inter"

# List stored specs
npx ibr memory list

# IBR checks these during every scan automatically

Authenticated Pages

npx ibr login http://localhost:3000/login   # opens browser, log in manually
npx ibr scan http://localhost:3000/dashboard --json  # validates with your auth
npx ibr logout                                 # clear saved auth

Verdicts

After ibr check, you get one of four results:

Verdict	Meaning	Action
`MATCH`	Nothing changed	You're done
`EXPECTED_CHANGE`	Changes look intentional	Review and continue
`UNEXPECTED_CHANGE`	Something changed that shouldn't have	Investigate
`LAYOUT_BROKEN`	Major structural issues	Fix before continuing

Programmatic API

import { compare } from '@tyroneross/interface-built-right';

const result = await compare({
  url: 'http://localhost:3000/dashboard',
  baselinePath: './baselines/dashboard.png',
});

console.log(result.verdict);     // "MATCH" | "EXPECTED_CHANGE" | ...
console.log(result.diffPercent); // 2.5
console.log(result.summary);    // "Header background changed. Layout intact."

Engine API (advanced)

import { EngineDriver, CompatPage } from '@tyroneross/interface-built-right/engine';

// Direct CDP engine access
const driver = new EngineDriver();
await driver.launch({ headless: true, viewport: { width: 1920, height: 1080 } });

// Navigate with stability detection
await driver.navigate('http://localhost:3000', { waitFor: 'stable' });

// Discover interactive elements (LLM-optimized)
const elements = await driver.discover({
  filter: 'interactive',
  serialize: true,        // compact format for context windows
  maxTokens: 4000,
});

// Find elements by intent (not CSS selectors)
const button = await driver.find('Submit', { role: 'button' });

// Assess page understanding quality
const understanding = await driver.assessUnderstanding();
if (understanding.needsScreenshot) {
  const screenshot = await driver.screenshot({ fullPage: true });
}

// Extract structured data
const data = await driver.extract({
  title: { role: 'heading', extract: 'text' },
  isLoggedIn: { role: 'button', label: 'logout', extract: 'exists' },
});

await driver.close();

Session-based workflow

import { InterfaceBuiltRight } from '@tyroneross/interface-built-right';

const ibr = new InterfaceBuiltRight({
  baseUrl: 'http://localhost:3000',
  outputDir: './.ibr',
  threshold: 1.0,
});

const { sessionId } = await ibr.startSession('/dashboard', {
  name: 'dashboard-update',
});

// After changes
const report = await ibr.check(sessionId);
console.log(report.analysis.verdict);

await ibr.close();

Configuration

Optional — create .ibrrc.json in your project root:

{
  "baseUrl": "http://localhost:3000",
  "outputDir": "./.ibr",
  "viewport": "desktop",
  "threshold": 1.0,
  "fullPage": true
}

Available viewports: desktop, laptop, tablet, mobile, iphone-14, iphone-14-pro-max

Mobile and device emulation (1.1.0+)

IBR emulates mobile and tablet devices end-to-end via CDP (no Playwright dependency). Three things happen on driver.launch(), in order, BEFORE the first navigate:

Emulation.setUserAgentOverride — so the initial HTML response sees a mobile UA
Emulation.setDeviceMetricsOverride — width, height, DPR, mobile: true
Emulation.setTouchEmulationEnabled — so navigator.maxTouchPoints > 0 and CSS @media (pointer: coarse) matches

`--viewport` presets

npx ibr scan https://example.com --viewport mobile --json
# viewport in JSON: { name: "mobile", width: 390, height: 844, deviceScaleFactor: 3, mobile: true }

Preset	Size	DPR	Mobile
`desktop`	1920 x 1080	1	false
`desktop-lg`	2560 x 1440	1	false
`desktop-sm`	1440 x 900	1	false
`laptop`	1366 x 768	1	false
`tablet`	820 x 1180 (iPad Air baseline)	2	true
`tablet-landscape`	1180 x 820	2	true
`mobile`	390 x 844 (iPhone 14 baseline)	3	true
`mobile-lg`	430 x 932	3	true

Pre-1.1.0 --viewport mobile parsed cleanly but rendered desktop (375 x 667 with no mobile flag and no UA override). If you previously worked around this by passing custom widths, you can switch to the preset.

`--device <name>` — canonical profiles

--device carries a full CDP profile (viewport + DPR + mobile + UA + touch). It wins over --viewport when both are given.

npx ibr scan http://localhost:3000 --device iphone-14 --json
npx ibr session:start http://localhost:3000 --device pixel-7

Device	Size	DPR	UA
`iphone-14`	390 x 844	3	iOS 17 Safari
`iphone-14-pro-max`	430 x 932	3	iOS 17 Safari
`pixel-7`	412 x 915	2.625	Android 14 Chrome
`ipad-air`	820 x 1180	2	iPad iOS 17 Safari
`ipad-pro-11`	834 x 1194	2	iPad iOS 17 Safari
`desktop-1440`	1440 x 900	1	(default Chrome)

Unknown --device names fail loudly: Error: Unknown --device "iphone-99". Known devices: iphone-14, .... Add more profiles in src/devices.ts.

Library use

import { EngineDriver, resolveDevice, deviceToViewport } from '@tyroneross/interface-built-right'

const profile = resolveDevice('iphone-14')
const driver = new EngineDriver()
await driver.launch({ headless: true, viewport: deviceToViewport(profile) })
await driver.navigate('https://example.com')

Troubleshooting

Problem	Fix
`Command not found: ibr`	Use `npx ibr --help`
Chrome not found	Install Google Chrome, or pass `chromePath` option
Auth state expired	`npx ibr login <url>`
Session not found	`npx ibr list` to see available sessions
`--viewport mobile` renders desktop (pre-1.1.0)	Upgrade to >= 1.1.0; mobile presets now set the CDP mobile flag + UA + touch
`Unknown --device "..."`	Run `npx ibr scan --help` to see the canonical device list, or add a profile to `src/devices.ts`

Requirements

Node.js 22+ (uses built-in WebSocket for CDP)
Google Chrome installed (uses system Chrome, no downloads needed)

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 304 Commits
.build-loop		.build-loop
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
adapters		adapters
agents		agents
archive/bundles		archive/bundles
assets/native/swift-templates		assets/native/swift-templates
commands		commands
dist		dist
docs		docs
examples		examples
hooks		hooks
mobile-ui		mobile-ui
mockups		mockups
references		references
scripts-plugin		scripts-plugin
scripts		scripts
skills		skills
src		src
templates		templates
test/ibr-build		test/ibr-build
universal		universal
web-ui		web-ui
.gitignore		.gitignore
.ibr-test.json		.ibr-test.json
.ibrrc.json		.ibrrc.json
.mcp.json		.mcp.json
.npmrc		.npmrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
INTEGRATION_USAGE.md		INTEGRATION_USAGE.md
LICENSE		LICENSE
NATIVE_SUPPORT_PROPOSAL.md		NATIVE_SUPPORT_PROPOSAL.md
PHASE-5-CHECKLIST.md		PHASE-5-CHECKLIST.md
PHASE-5-SUMMARY.md		PHASE-5-SUMMARY.md
README.md		README.md
VERSIONING.md		VERSIONING.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Interface Built Right

Design Workflow

Design Director

Imagegen Concepts

Web Design Routing

iOS Design System

Two-Tier Architecture

Tier 1 — Deterministic Rule Engine (no LLM)

ibr ask — focused verdicts (v3 thesis M1)

Tier 2 — Sensor Layer (structured summaries)

Hydration Waiting

Live Sessions with Auto-Capture

Architecture

What's New in v1.4.0

What's New in v0.7.0

What's New in v1.0.0

What's New in v0.9.0-alpha

The Problem

How It Works

Quick Start

Validate UI (primary workflow):

Regression check:

Sandbox-friendly browser attach

Setup as Agent Plugins

Claude Code

Codex

What IBR Does For You (Plugin Hooks)

What IBR Scan Returns

Element Data (per interactive element)

Page-Level Data

Scan Data vs Screenshots

Where IBR scan wins

Where screenshots win

Best practice: combine both

CLI Reference

Core Commands

Interactive Sessions

Memory (Design Specs)

Authenticated Pages

Verdicts

Programmatic API

Configuration

Mobile and device emulation (1.1.0+)

--viewport presets

--device <name> — canonical profiles

Library use

Troubleshooting

Requirements

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`ibr ask` — focused verdicts (v3 thesis M1)

`--viewport` presets

`--device <name>` — canonical profiles

Packages