design-validation

name	design-validation
description	Use when the user asks to audit UI, validate the build, check accessibility, find regressions, compare before/after, or run a full scan — post-build verification pass across the interface.
version	0.5.0
user-invocable	false

Design Validation with IBR

Run structured post-build audits against live pages and native simulators. Validation is distinct from implementation — it is a deliberate verification pass after work is complete, not an inline check during building. The goal is to surface issues that implementation scanning may have missed and confirm the build matches spec.

Scope of Validation

A full validation pass covers:

• Design contract — implementation matches design-intent.json, platform archetype, target roles, and validation plan
• Interactivity — all buttons, links, and forms have wired handlers and real targets
• Accessibility — all interactive elements have labels, touch targets meet size minimums, keyboard access works
• Semantic state — page intent is correct, no stuck loading or error states, available actions match expectations
• Console health — no JavaScript errors or warnings during page load
• Structure — no orphaned elements, disabled states are visually distinct, layout is intact

Run a complete pass, not a spot check. Issue categories compound — an inaccessible button that also lacks a handler is two separate failures, not one.

Primary Tool: ibr scan

Call ibr scan to read the full state of a live page.

Input: url (required), format (optional: "json"), viewport (optional), waitFor (optional CSS selector)

Returns:

• Verdict: PASS, ISSUES, or FAIL
• Per-element data: selector, tagName, bounds, computedStyles, interactive status, a11y attributes
• Interactivity audit: buttons with/without handlers, links with real vs placeholder hrefs, form submit handlers
• Semantic state: pageIntent, auth/loading/error states, available actions
• Console errors and warnings
• Issue list with severity, category, description, and selector

Reading Verdicts

Verdict	Meaning
PASS	No issues found — implementation is clean
ISSUES	Issues detected — review by severity and decide whether to fix or accept
FAIL	Critical issues — broken handlers, console errors, inaccessible elements — must fix

Do not treat ISSUES as acceptable without reading the issue list. Severity matters: low-severity structural notes may be acceptable in context; missing handlers are not.

Issue Categories

Category	Examples	Severity
interactivity	Button without handler, form without submit action, placeholder href="#"	High
accessibility	Missing aria-label, touch target below 44px/44pt, no keyboard focus indicator	High
semantic	Page stuck in loading state, wrong pageIntent, actions missing from expected set	Medium
console	JavaScript errors or unhandled promise rejections on page load	High
structure	Orphaned elements, disabled without visual differentiation, invisible interactive elements	Low–Medium

Address high-severity issues before closing the audit. Document accepted medium/low items with rationale.

Accessibility Audit

Accessibility validation is a first-class concern, not an afterthought. Check every interactive element:

• a11y.ariaLabel is present and descriptive (not generic like "button" or "click here")
• a11y.role is appropriate for the element type
• bounds meet minimum touch target size: 44px for web, 44pt for native iOS/watchOS
• Focusable elements are reachable via keyboard (Tab order)
• Error messages are associated with their inputs via a11y.ariaDescribedBy
• Icons without visible text have an accessible label

Report each accessibility failure with its selector, the missing attribute, and the expected value.

Regression Checking

Use ibr compare to verify that changes did not introduce unintended side effects.

Setup: Capture a baseline

Before any change that may affect layout or visual state, call ibr snapshot.

Input: url (required), name (required — use a descriptive label like "pre-nav-refactor")

The snapshot records computed element state at that point in time.

After changes: Run comparison

Call ibr compare to diff the current page against the baseline.

Returns verdicts:

Verdict	Meaning	Action
MATCH	No changes detected	Confirm expected — if changes were made, baseline may be stale
EXPECTED_CHANGE	Changes detected, appear intentional	Review diff regions and sign off
UNEXPECTED_CHANGE	Elements moved or changed outside the intended scope	Investigate and fix
LAYOUT_BROKEN	Major structural displacement	Treat as a blocker — do not ship

Report the diff regions for any non-MATCH verdict. For UNEXPECTED_CHANGE, identify which edit introduced the regression and revert or fix it.

Managing sessions

Call ibr list_sessions to see all active baseline sessions. Use when auditing across multiple features or returning to work after a pause.

Native iOS/watchOS/macOS Validation

For Swift/SwiftUI projects, validate against the running simulator rather than the browser.

Scan the simulator

Call ibr native_scan to extract the accessibility element tree and validate layout constraints.

Input: device (optional — simulator name like "Apple Watch Series 9" or "iPhone 16 Pro")

Checks performed:

• Touch targets: 44pt minimum on all interactive elements
• Accessibility labels on all tappable elements
• watchOS: no more than 7 interactive elements per screen
• watchOS: no horizontal content overflow beyond the device viewport

Report each violation with the element identifier and the measured vs expected value.

Native regression

Call ibr native_snapshot before simulator changes, then ibr native_compare after. The same verdict table applies as web comparison.

List simulators

Call ibr native_devices to see all simulators and their boot status. Confirm the target device is booted before scanning. A scan against an unbooted device will return no elements.

macOS apps

Call ibr scan_macos to audit a running macOS application via its accessibility tree. Pass the app name as the target identifier.

Audit Workflow

A complete post-build validation pass:

1. Read design intent — load .ibr/builds/<topic>/design-intent.json and specialists/validation-plan.md when present
2. Scan all routes — call ibr scan on each page in the application, not just the primary route
3. Triage the issue list — sort by severity; address all high-severity issues before moving to medium
4. Accessibility pass — verify every interactive element has a label, role, and adequate touch target
5. Interactivity pass — confirm every button, link, and form has a working handler and real target
6. Console pass — confirm zero JavaScript errors on page load for every route
7. Reference pass — validate wireframe-target semantically and visual-target visually when target roles exist
8. Regression check — call ibr compare if baselines exist; verify no unexpected changes

Do not close the audit until all high-severity issues are resolved or explicitly accepted with documented rationale.

Principle Enforcement

When .ibr/design-system.json is active, the scan automatically enforces Calm Precision principles:

Principle	What it checks	Default severity
Gestalt	Individual borders on list items, ungrouped related elements	error
Signal-to-Noise	Status elements with heavy background colors instead of text color	error
Content-Chrome	Content area ratio below 70%	warn
Cognitive Load	More than 7 interactive elements in a visual group	warn
Fitts	Primary action buttons below 120px width	warn
Hick	More than 5 visible choices without progressive disclosure	warn
Functional Integrity	Interactive-looking elements without real action/destination	error
Mobile-First	Touch targets, input sizing, and mobile ordering issues	error/warn
Voice	Generic errors, vague loading, long button labels	warn
Data Resilience	Missing empty/error/loading states or unlabeled metrics	warn

Principle violations appear in the designSystem.principleViolations array of the scan result. Each violation includes the rule ID, element selector, and a fix suggestion.

To adjust severity: edit .ibr/design-system.json → principles.calmPrecision.severity. Set any principle to "off" to disable it.

Token Compliance

When design tokens are configured, the scan checks all rendered elements against the token specification:

• Colors: text color and background-color against tokens.colors
• Font sizes: computed font-size against tokens.typography.fontSizes
• Font weights: computed font-weight against tokens.typography.fontWeights
• Spacing: gap, padding, margin against tokens.spacing array
• Border radius: computed border-radius against tokens.borderRadius
• Touch targets: interactive element size against tokens.touchTargets.min

Token violations appear in designSystem.tokenViolations. Each reports the element, property, expected token value, and actual value.

The designSystem.complianceScore (0-100) reflects the percentage of checked properties that match tokens. A score of 100 means every rendered value matches the design system.

Change Tracking in CI Context

When auditing after a PR or deployment:

1. Ensure a pre-change baseline exists (ibr list_sessions to confirm)
2. Run ibr compare to surface any layout regressions
3. Run ibr scan on all affected routes
4. Report: verdict per route, issue count by severity, regression status (MATCH/UNEXPECTED_CHANGE)

If no baseline exists, create one now and note that regression comparison is not available for this cycle.

Audit Verdict Summary Format

When reporting audit results, use this structure:

Route: /example
  Design contract: PASS | ISSUES | not available
  Scan verdict: PASS | ISSUES | FAIL
  Issues: [count] ([high] high, [med] medium, [low] low)
  Regression: MATCH | EXPECTED_CHANGE | UNEXPECTED_CHANGE | LAYOUT_BROKEN | no baseline
  References: wireframe PASS|ISSUES|n/a; visual MATCH|ISSUES|n/a
  Blockers: [list high-severity issues or "none"]

Provide one block per route. Summarize total blocker count at the end. A build is ready to ship when all routes return PASS or ISSUES with zero high-severity items and regression status is MATCH or EXPECTED_CHANGE.

IBR vs Screenshot vs Interactive Session

Task	Tool
Full accessibility and handler audit	ibr scan
Visual regression and rendering defects	Screenshot
Multi-step flow validation (login, checkout)	ibr session (interactive-testing skill)
Layout change tracking	ibr snapshot + ibr compare
Native touch target and a11y audit	ibr native_scan

ibr — design validation